<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Progress Bar Examples - Ratings</title>
<!-- css -->
<link rel="stylesheet" type="text/css" href="../../build/reset-fonts-grids/reset-fonts-grids.css">
<link rel="stylesheet" type="text/css" href="../../build/base/base.css">
<link rel="stylesheet" type="text/css" href="../../build/progressbar/assets/skins/sam/progressbar.css">
<link rel="stylesheet" type="text/css" href="../../build/datatable/assets/skins/sam/datatable.css">


<link rel="stylesheet" type="text/css" href="http://developer.yahoo.com/yui/assets/dpSyntaxHighlighter.css">

<!-- js -->
<script type="text/javascript" src="../../build/yahoo-dom-event/yahoo-dom-event.js"></script>
<script type="text/javascript" src="../../build/animation/animation-min.js"></script>
<script type="text/javascript" src="../../build/element/element-min.js"></script>

<script type="text/javascript" src="../../build/get/get-min.js"></script>
<script type="text/javascript" src="../../build/datasource/datasource-min.js"></script>
<script type="text/javascript" src="YQLDataSource.js"></script>
<script type="text/javascript" src="../../build/datatable/datatable-min.js"></script>

<script type="text/javascript" src="../../build/progressbar/progressbar-debug.js"></script>


<style type="text/css">

.yui-skin-sam .ratings {
	width:100px;
	height:20px;
	background:white none repeat 0 0;
}
.yui-skin-sam .ratings .yui-pb-bar  {
	background: transparent url(star.png) repeat-x 0 0;
}

/* Just a little decoration for the page, not relevant to the usage of the progress bar */

code {
	background-color:#e0e0e0;
	border:thin solid #c0c0c0;
	white-space:pre;
	font-size:10px;
}

.dp-highlighter th, .dp-highlighter td {
	border:0;
	padding:0;
}
.dp-highlighter .line1, .dp-highlighter  .line2 {
	padding-left:10px;
	white-space:nowrap;
}

</style>
</head>
<body class="yui-skin-sam">
	<div id="doc">
		<div id="hd">
			<h1>Progress Bar Examples - Ratings</h1>
			<p>The ProgressBar can be used within other widgets.   
			Here we are using Yahoo! Query Language, <a href="http://developer.yahoo.com/yql/">YQL</a> 
			looking for Sushi restaurants in San Francisco, CA. and displaying the information in a 
			<a href="http://developer.yahoo.com/yui/datatable/">YUI DataTable</a>.  
			We are showing some of the plain text fields as such, but for the ratings of the restaurants
			we are using the ProgressBar.</p>
		</div>
		<div id="bd">
			<div id="Container"></div>
		</div>
		<div id="ft">
			<p>The Ratings from the query are being represented by YUI ProgressBars.</p>
			<p>YQL allows to query some of YAHOO! vast databases using a language similar to SQL. 
			The query for this examples is:</p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				select Title,Address,Phone, Rating.AverageRating from local.search 
					where query="sushi" and location="san francisco, ca"
			</textarea>
			<p>which can be tested by pasting it into the <a href="http://developer.yahoo.com/yql/console/">YQL Console</a>. 
			YQL replies directly to an HTTP request with the search results either in 
			<a href="http://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20local.search%20where%20query%3D%22sushi%22%20and%20location%3D%22san%20francisco%2C%20ca%22&format=xml">XML</a> 
			or <a href="http://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20local.search%20where%20query%3D%22sushi%22%20and%20location%3D%22san%20francisco%2C%20ca%22&format=json&callback=cbfunc">JSON</a> format,
			this last being suitable to be used with the <a href="http://developer.yahoo.com/yui/get/">YUI Get utility</a>.
			However, we are using a freely available subclass of <a href="http://developer.yahoo.com/yui/datasource/">YUI DataSource</a> which handles
			the communication with YQL for us.</p>
			<p>The code to build the DataTable on that query is:</p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				var dt = new YAHOO.widget.DataTable(
					'Container',
					[
						{key:"Title",sortable:true},
						{key:"Address",sortable:true},
						{key:"Phone",sortable:true},
						{key:"Rating.AverageRating",label:"Rating",	sortable:true}
					],
					new YAHOO.util.YQLDataSource(),
					{
						initialRequest:'select Title,Address,Phone, Rating.AverageRating from local.search ' +
							'where query="sushi" and location="san francisco, ca"'
					}
				);
			</textarea>
			<p>We are drawing a simple DataTable with four columns, the first three of them, Title, Address and Phone are simple
			text fields that are displayed just as they are received.  The fourth field is the one we are interested in.
			The query returns that field nested within the structure of each record.  The property <code>Rating</code> is actually 
			an object which contains several other properties and from those we choose <code>AverageRating</code>, thus, we
			use the composite field name <code>Rating.AverageRating</code> both in the query and in the <code>key</code> for the
			column definitions.  Since that is not an acceptable label for the column header, we have to provide one. 
			Initially, this will also be drawn as a simple text field. All columns are sortable, even the Ratings column.</p>

			<p>We will listen to DataTable's <code>renderEvent</code> to know when the table has been drawn.  
			At that point, we will search for the cells containing the rating and replace it with the ProgressBar:<p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				dt.on('renderEvent',function() {
					YAHOO.util.Dom.getElementsByClassName(
						'yui-dt-col-' + this.getColumn("Rating.AverageRating").getSanitizedKey(),
						'td', 
						this.getTbodyEl(),
						function (tdEl) {
							var elLiner = this.getTdLinerEl(tdEl), 
								val = parseFloat(elLiner.innerHTML);
							elLiner.innerHTML = '';
							// Here we draw the progerssBar:
							(new YAHOO.widget.ProgressBar({value:val,maxValue:5, className:'ratings'})).render(elLiner);
						},
						this,
						true
					);
				});
			</textarea>
			<p>The DataTable marks each cell with a className with a prefix of <code>'yui-dt-col-'</code> followed by its sanitized column key value, 
			to ensure it is a valid className.  We use Dom's <code>getElementsByClassName</code> to locate each &lt;td&gt; element of that className
			and execute a function that locates the liner element, which is the one that actually contains the value displayed.
			We read the value into variable <code>val</code>, empty the cell and finally draw the ProgressBar.  
			This is done in the single line that takes the value just read and renders it in the same liner element.</p>
			
			<p>The stars come from this single star <img src="star.png" /> which the ProgressBar tiles until it fills the allotted space.
			The style settings for this example is:</p>
			<textarea name="code" class="JScript" cols="60" rows="1">
				.yui-skin-sam .ratings {
					width:100px;
					height:20px;
					background:white none repeat 0 0; 
				}
				.yui-skin-sam .ratings .yui-pb-bar  {
					background: transparent url(star.png) repeat-x 0 0;
				}
			</textarea>
			<p>We are using <code>.yui-skin-sam .ratings</code> as a selector in all the styles.  
			We use the <code>yui-skin-sam</code> for basic skinning in all the page, including the DataTable, so we need to
			override some of its settings.  We gave the <code>ratings</code> className to all the ProgressBars
			as one of the arguments in their instantiation.  Since the star is in a square 20px on a side and ratings go up to 5,
			we draw the bars of 100px * 20px and, since the icon fades to white, we set the background to white as well.
			In the second definition, we set the background image for the bar itself to the star icon.  
			We leave the borders that the SAM skin provides.</p>
			
			<p>A simpler way might have been to use the formatter function on the columns definition of the DataTable to draw
			the ProgressBar for each cell when building the table.  Unfortunately, the formatter is called while the DataTable row
			has not been added to the DOM document yet.  At that point, the CSS styles above wouldn't work because the <code>yui-skin-sam</code>
			is in the document body so the width and height wouldn't be set and all the rest of the elements would be resized incorrectly.</p>
			
			<p>We are being a little careless about the ProgressBar instances we are leaving behind.  Just as with most YUI components
			the ProgressBar has a <code>destroy</code> method which makes certain nothing is left behind taking up memory.  
			In some operations like sorting, the DataTable draws each cell anew, ignoring its previous contents.  Though this
			takes care of the HTML markup produced, it does not frees the memory taken by the ProgressBar object instances themselves.
			In this example we are keeping no reference to the ProgressBars created nor to any of the other components, for that matter.
			We should keep this references and make sure to run through them calling the <code>destroy</code> method when the DataTable
			is about to destroy them.</p>
		</div>
	</div>
	
<script  type="text/javascript">

	YAHOO.util.Event.onDOMReady(function () {
		var dt = new YAHOO.widget.DataTable(
			'Container',
			[
				{key:"Title",sortable:true},
				{key:"Address",sortable:true},
				{key:"Phone",sortable:true},
				{key:"Rating.AverageRating",label:"Rating",	sortable:true}
			],
			new YAHOO.util.YQLDataSource(),
			{
				initialRequest:'select Title,Address,Phone, Rating.AverageRating from local.search where query="sushi" and location="san francisco, ca"'
			}
		);

		dt.on('renderEvent',function() {
			YAHOO.util.Dom.getElementsByClassName(
				'yui-dt-col-' + this.getColumn("Rating.AverageRating").getSanitizedKey(),
				'td', 
				this.getTbodyEl(),
				function (tdEl) {
					var elLiner = this.getTdLinerEl(tdEl), val = parseFloat(elLiner.innerHTML);
					elLiner.innerHTML = '';
					(new YAHOO.widget.ProgressBar({value:val,maxValue:5, className:'ratings'})).render(elLiner);
				},
				this,
				true
			);
		});
	});
</script>
<script type="text/javascript" src="http://developer.yahoo.com/yui/assets/dpSyntaxHighlighter.js"></script>
<script type="text/javascript" language="javascript">dp.SyntaxHighlighter.HighlightAll('code');</script>
</body>
</html>
	
